<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="resource-type" content="document">
<meta name="description" content="Porting guide: autoconf">
<meta name="keywords" content="openbsd,ports,autoconf">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 2004 by OpenBSD.">
<title>Porters' handbook: dealing with configuration files</title>
</head>
<body>
<img height="30" width="141" src="../images/smalltitle.gif" alt="[OpenBSD]"> 
<h1>Porters handbook: dealing with configuration files</h1>

Packages should only install files under <code>${PREFIX}</code>, which is
<code>/usr/local</code> by default.
On the other hand, the OpenBSD policy is to install most configuration files
under <code>${SYSCONFDIR}</code>, which is <code>/etc</code> by default.
</p>
<i>Note that it is perfectly acceptable for a binary package to have both ${PREFIX} and
${SYSCONFDIR} hardcoded: PREFIX and SYSCONFDIR are mostly user settings
that influence the build of the package.</i>
</p>
<h2>@sample explained</h2>
Packing-lists contain a specific <code>@sample</code> mechanism to deal with
configuration files:
<ul>
<li>During fake installation, the port should install a sample configuration 
file, for instance as ${PREFIX}/share/examples/PKGNAME/foo.rc.
<li>The packing-list should contain a <code>@sample ${SYSCONFDIR}/foo.rc</code>
right under the sample configuration file.
<li>During installation, the default example configuration file will be copied 
into the actual location where the configuration file should live.
<li>During updates and deinstallation, an existing configuration file will be
compared with the default example file. If they differ, the package tools will
inform the user and let him perform the update/removal himself. If they are
identical, the package tools know they can proceed and update/remove the
configuration files without any further precautions.
</ul>
<h2>more @sample specificities</h2>
Contrary to other files in a packing-list, <code>@sample</code> entries can
have an absolute path name.
</p>
Some big packages will also need their own configuration directory,
<code>@sample ${SYSCONFDIR}/directory/</code> will deal with that.
</p>
Using <code>@sample directory/</code> to create port specific directories
that do not hold any configuration files is perfectly good style.
<code>@sample</code> correctly interprets correct <code>@mode</code>, 
<code>@owner</code>, <code>@group</code> annotations.   This can be a
bit cumbersome, because you will often need to switch back and forth
between a default mode and a configuration file specific mode.
<h2>Special tricks</h2>
<code>make update-plist</code> knows how to copy <code>@sample</code>
annotations over, but it does not know how to create them, so they have
to be written in the first place.
</p>
Note the distinction between configuration files and example configuration
files: the port must be configured to find its files under 
<code>${SYSCONFDIR}</code>, it is only the fake installation stage that must
put stuff under <code>${PREFIX}/share/examples</code>. 
One simple way to handle that is to copy the files over in a <code>post-install</code>.
</p>
A neat trick which often works is to look at a program's makefile, and override
the configuration directory  in the fake installation stage by using specific
<code>FAKE_FLAGS</code>, for instance: 
<pre>FAKE_FLAGS=DESTDIR=${WRKINST} sysconfdir=${WRKINST}${TRUEPREFIX}/share/examples/PKGNAME
</pre>
You just need to watch out for programs that write the configuration directory
down in specific files during their install stage.
<h2>Examples</h2>
<ul>
<li>The security/integrit port uses a configuration directory with a few files.
Its packing-list looks like this:
<pre>
@comment $OpenBSD: config.html,v 1.2 2008/03/15 10:36:25 sthen Exp $
bin/i-ls
@info info/integrit.info
@man man/man1/i-ls.1
@man man/man1/i-viewdb.1
@man man/man1/integrit.1
sbin/i-viewdb
sbin/integrit
share/doc/integrit/
share/doc/integrit/README
share/doc/integrit/crontab
share/doc/integrit/install_db
share/doc/integrit/integrit_check
share/doc/integrit/viewreport
share/examples/integrit/
@sample ${SYSCONFDIR}/integrit/
share/examples/integrit/root.conf
@sample ${SYSCONFDIR}/integrit/root.conf
share/examples/integrit/src.conf
@sample ${SYSCONFDIR}/integrit/src.conf
share/examples/integrit/usr.conf
@sample ${SYSCONFDIR}/integrit/usr.conf
</pre>
<li>The security/nessus port uses <code>@sample dir/</code> to create private directories.
<pre>
...
sbin/uninstall-nessus
@sample ${SYSCONFDIR}/nessus/
@mode 0700
@sample /var/nessus/
@sample /var/nessus/jobs/
@sample /var/nessus/logs/
@sample /var/nessus/users/
@extraunexec rm -fr %D/lib/nessus/plugins/*
@extraunexec rm -fr %D/nessus
@extraunexec rm -fr /var/nessus
</pre>
<li>The sysutils/nut port uses a specific owner for its configuration files.
<pre>
@comment $OpenBSD: config.html,v 1.2 2008/03/15 10:36:25 sthen Exp $
@conflict upsd-*
@newuser ${NUT_USER}:${NUT_ID}:::UPS User:/var/empty:/sbin/nologin
...
share/examples/nut/
@sample ${SYSCONFDIR}/nut/
@owner ${NUT_USER}
share/examples/nut/ups.conf
@sample ${SYSCONFDIR}/nut/ups.conf
share/examples/nut/upsd.conf
@mode 600
@sample ${SYSCONFDIR}/nut/upsd.conf
@mode
share/examples/nut/upsd.users
@mode 600
@sample ${SYSCONFDIR}/nut/upsd.users
@mode
share/examples/nut/upsmon.conf
@mode 600
@sample ${SYSCONFDIR}/nut/upsmon.conf
@mode
share/examples/nut/upssched.conf
@sample ${SYSCONFDIR}/nut/upssched.conf
@mode 700
@sample /var/db/nut/
@mode
@owner
share/ups/
share/ups/cmdvartab
share/ups/driver.list
</pre>
  <hr>
  <a href="../index.html"><img height=24 width=24 src=../back.gif border=0 alt=OpenBSD></a> 
  <a href="mailto:www@openbsd.org">www@openbsd.org</a>
<br><small>$OpenBSD: config.html,v 1.2 2008/03/15 10:36:25 sthen Exp $</small>
 </body>
</html>
